Nregion synchronous commit feature #47757

mbhaskar · 2026-01-20T23:43:55Z

Description

This PR adds support for nregion synchronous commit for less than strong consistency to the SDK

Major changes

Added isNRegionSynchronousCommitEnabled to DatabaseAccount to get if the feature is enabled on the account. This is then populated on the RequestContext for write requests so that it can be read from ConsistencyWriter.
Deserialize GlobalNRegionCommittedGLSN from backend RNTBD response headers
Prior to this, we used to issue barrier requests only for global strong account/requests. This PR introduce barrier request calls for write request when N-Region Synchronous commit is enabled for the account and N-Region Committed LSN is returned for less than strong consistency to enforce barrier writes

Testing

Added unit tests using mock for global strong and n-region barrier requests for success and failure scenarios
Tested manually on a live account that has n-region commit enabled

##Reference
Azure/azure-cosmos-dotnet-v3#5401

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

Adding unit tests Refactoring and cleanup

# Conflicts: # sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

Copilot

Pull request overview

This PR adds support for N-region synchronous commit for less than strong consistency levels in the Azure Cosmos DB Java SDK. The feature introduces barrier write requests similar to global strong consistency, but specifically for N-region commit scenarios when the account has this capability enabled.

Changes:

Added deserialization of GlobalNRegionCommittedGLSN header from backend RNTBD responses
Added isNRegionSynchronousCommitEnabled property to DatabaseAccount and propagated it through GlobalEndpointManager and request context
Refactored ConsistencyWriter barrier request logic to support both global strong writes and N-region synchronous commit scenarios
Added comprehensive unit tests for the new barrier request scenarios

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
RntbdConstants.java	Added GlobalNRegionCommittedGLSN response header constant with ID 0x0078
RntbdResponseHeaders.java	Added deserialization support for GlobalNRegionCommittedGLSN header
WFConstants.java	Added GLOBAL_N_REGION_COMMITTED_GLSN backend header constant
StoreResponse.java	Added getNumberOfReadRegions() method to retrieve number of read regions from response headers
ConsistencyWriter.java	Refactored barrier request logic to support both global strong and N-region commit scenarios with dedicated helper methods
BarrierType.java	New enum to distinguish between barrier types (NONE, GLOBAL_STRONG_WRITE, N_REGION_SYNCHRONOUS_COMMIT)
RxDocumentClientImpl.java	Set NRegionSynchronousCommitEnabled flag in request context for write operations
RMResources.java	Added error message for N-region commit barrier not met scenarios
HttpConstants.java	Added sub-status code for N-region commit write barrier failures
GlobalEndpointManager.java	Added method to retrieve N-region synchronous commit enabled status from database account
DocumentServiceRequestContext.java	Added fields for N-region commit enabled flag and barrier type, renamed globalStrongWriteResponse to cachedWriteResponse
DatabaseAccount.java	Added method to check if N-region synchronous commit is enabled on the account
Constants.java	Added ENABLE_N_REGION_SYNCHRONOUS_COMMIT property constant
ConsistencyWriterTest.java	Added comprehensive unit tests for global strong and N-region commit barrier scenarios

Comments suppressed due to low confidence (1)

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/DocumentServiceRequestContext.java:170

The clone method does not copy the two new fields (nRegionSynchronousCommitEnabled and barrierType) added to DocumentServiceRequestContext. When a context is cloned, these fields will be null/default in the cloned instance, which could lead to incorrect behavior during request processing. Add the following assignments to the clone method:
context.nRegionSynchronousCommitEnabled = this.nRegionSynchronousCommitEnabled;
context.barrierType = this.barrierType;

    public DocumentServiceRequestContext clone() {
        DocumentServiceRequestContext context = new DocumentServiceRequestContext();
        context.forceAddressRefresh = this.forceAddressRefresh;
        context.forceRefreshAddressCache = this.forceRefreshAddressCache;
        context.requestChargeTracker = this.requestChargeTracker;
        context.timeoutHelper = this.timeoutHelper;
        context.resolvedCollectionRid = this.resolvedCollectionRid;
        context.sessionToken = this.sessionToken;
        context.quorumSelectedLSN = this.quorumSelectedLSN;
        context.globalCommittedSelectedLSN = this.globalCommittedSelectedLSN;
        context.cachedWriteResponse = this.cachedWriteResponse;
        context.originalRequestConsistencyLevel = this.originalRequestConsistencyLevel;
        context.readConsistencyStrategy = this.readConsistencyStrategy;
        context.resolvedPartitionKeyRange = this.resolvedPartitionKeyRange;
        context.resolvedPartitionKeyRangeForCircuitBreaker = this.resolvedPartitionKeyRangeForCircuitBreaker;
        context.resolvedPartitionKeyRangeForPerPartitionAutomaticFailover = this.resolvedPartitionKeyRangeForPerPartitionAutomaticFailover;
        context.regionIndex = this.regionIndex;
        context.usePreferredLocations = this.usePreferredLocations;
        context.locationIndexToRoute = this.locationIndexToRoute;
        context.regionalRoutingContextToRoute = this.regionalRoutingContextToRoute;
        context.performLocalRefreshOnGoneException = this.performLocalRefreshOnGoneException;
        context.effectivePartitionKey = this.effectivePartitionKey;
        context.performedBackgroundAddressRefresh = this.performedBackgroundAddressRefresh;
        context.cosmosDiagnostics = this.cosmosDiagnostics;
        context.resourcePhysicalAddress = this.resourcePhysicalAddress;
        context.throughputControlRequestContext = this.throughputControlRequestContext;
        context.replicaAddressValidationEnabled = this.replicaAddressValidationEnabled;
        context.endToEndOperationLatencyPolicyConfig = this.endToEndOperationLatencyPolicyConfig;
        context.unavailableRegionsForPartition = this.unavailableRegionsForPartition;
        context.crossRegionAvailabilityContextForRequest = this.crossRegionAvailabilityContextForRequest;
        return context;

.../src/test/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriterTest.java

...e-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/StoreResponse.java

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

.../src/test/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriterTest.java

Copilot · 2026-01-20T23:54:28Z

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java

                            options.setPartitionKeyDefinition(documentCollectionValueHolder.v.getPartitionKey());

                            request.requestContext.setCrossRegionAvailabilityContext(crossRegionAvailabilityContextForRequest);
+                            request.requestContext.setNRegionSynchronousCommitEnabled(this.globalEndpointManager.getNRegionSynchronousCommitEnabled());


The setNRegionSynchronousCommitEnabled is only being set in the createDocument flow (line 2692), but N-region synchronous commit should apply to all write operations (replace, upsert, delete, patch). Based on the pattern where setCrossRegionAvailabilityContext is called in multiple places throughout this file (lines 2253, 2691, 3077, 3377, 3610, 3783, 3972, etc.), setNRegionSynchronousCommitEnabled should be set consistently in all similar places where write operations occur to ensure the feature works correctly for all write request types.

...cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/GlobalEndpointManager.java

...zure-cosmos/src/main/java/com/azure/cosmos/implementation/DocumentServiceRequestContext.java

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

…ntation/DocumentServiceRequestContext.java Co-authored-by: Copilot <[email protected]>

Co-authored-by: Copilot <[email protected]>

FabianMeiswinkel · 2026-01-22T11:14:41Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

-    private Mono<Boolean> waitForWriteBarrierAsync(
+    private String getErrorMessageForBarrierRequest(RxDocumentServiceRequest request) {
+        if (request.requestContext.getBarrierType() == BarrierType.N_REGION_SYNCHRONOUS_COMMIT) {
+            return String.format("ConsistencyWriter: Write barrier has not been met for n region synchronous commit request. SelectedGlobalCommittedLsn: %s",


Log value of n - how many regions have to commit is configurable (should be part of the account metadata)?

Wanted to keep this consistent with the log message from .net. Not required?

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

jeet1995 · 2026-01-22T22:46:05Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

            globalCommittedLsn.v = Long.parseLong(headerValue);
        }
+        else if ((headerValue = response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN)) != null) {
+            globalCommittedLsn.v = Long.parseLong(headerValue);


I was wondering if we need a separate property in the diagnostic string for N-Region Committed LSN (to represent the LSN) and also account-level N-Region Commit enablement.

jeet1995 · 2026-01-22T22:47:52Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java


                    if (!v) {
-                        logger.info("ConsistencyWriter: Write barrier has not been met for global strong request. SelectedGlobalCommittedLsn: {}", request.requestContext.globalCommittedSelectedLSN);
+                        logger.info(this.getErrorMessageForBarrierRequest(request));


I wonder if error (if unrecoverable) or warn (if recoverable) is the better choice here (not introduced by this PR but nevertheless).

Changed it to warn. But would'nt changing an existing log effect anything? Although not an api, isnt this sort of a breaking change? if some one is actually filtering for these logs?

jeet1995 · 2026-01-22T23:12:35Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

+            request.requestContext.setBarrierType(BarrierType.N_REGION_SYNCHRONOUS_COMMIT);
+            return true;
+        }
+        request.requestContext.setBarrierType(BarrierType.NONE);


What is the barrier expectation or that of wrapping write operation when is isNRegionSynchronousCommitBarrierRequest evaluates to false and barrier is required due to some weird response from the backend? Are we failing the wrapping write in a certain way?

This would fail in the same way we fail a Global strong request

mbhaskar added 5 commits January 9, 2026 18:44

Adding support for nregion commit feature

793b176

Adding nregion header serialization in RNTBD

1351016

Adding unit tests Refactoring and cleanup

Cleaning up test

c87d4ad

Merge branch 'master' into nregioncommit

9633801

# Conflicts: # sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

Test cleanup and refactoring

1a8e02c

Copilot AI review requested due to automatic review settings January 20, 2026 23:43

mbhaskar requested review from a team and kirankumarkolli as code owners January 20, 2026 23:43

github-actions bot added the Cosmos label Jan 20, 2026

Copilot started reviewing on behalf of mbhaskar January 20, 2026 23:44 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

mbhaskar and others added 5 commits January 20, 2026 16:14

Update sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/impleme…

1b17110

…ntation/DocumentServiceRequestContext.java Co-authored-by: Copilot <[email protected]>

Update code doc

e703663

Co-authored-by: Copilot <[email protected]>

adding unit test group

4c025be

Co-authored-by: Copilot <[email protected]>

Fixing imports issue caused by copilot

c9b55ef

fixing tests

5a85467

FabianMeiswinkel reviewed Jan 22, 2026

View reviewed changes

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java Outdated Show resolved Hide resolved

jeet1995 reviewed Jan 22, 2026

View reviewed changes

Implementing PR comments

4375020

Nregion synchronous commit feature #47757

Are you sure you want to change the base?

Nregion synchronous commit feature #47757

Uh oh!

Conversation

mbhaskar commented Jan 20, 2026

Description

Major changes

Testing

All SDK Contribution checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeet1995 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeet1995 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jeet1995 Jan 22, 2026 •

edited

Loading

jeet1995 Jan 22, 2026 •

edited

Loading